Magnum One

home *** CD-ROM | disk | FTP | other *** search

/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d1 / diredit.arc / DIREDIT.DOC next >

Wrap

Text File | 1989-01-19 | 35.7 KB | 671 lines

Documentation for DIREDIT V1.51 Copyright 1986, P. R. Fletcher ________________________________ _______________________________ USER-SUPPORTED SOFTWARE _______________________ Much of the software which is available for your computer is produced and sold on the assumption that you are a crook and that you will take any available opportunity to cheat software writers and vendors out of their rightful reward. Such software is copy-protected within an inch of its (and your computer's) life and is priced at a level which still guarantees its producers a profit even if four or five illegal copies are made for each one sold. User-supported software is different. You may have got a copy of this program free from a friend or a bulletin board or (for a nominal fee) from a users' group or software library. In any case, you have a perfectly legal copy. You are encouraged to make as many copies of the package as you like and to distribute them to all your friends. If, after trying the program out, you find that it is useful and want to continue to keep and use it, you must register your copy by sending the registration fee ($20.00, unless you are already a registered user of HDTEST, in which case it is $10.00) together with the completed registration form, to the address on the form. Only your conscience can make you do this (although you are ____ probably breaking the law if you don't), but bear in mind that the distributors of "user-supported" software are making the assumption that you are honest and willing to pay a reasonable price for a useful program, many commercial software vendors, on the other hand, would apparently rather believe you are a crook. You can decide who you would rather prove right. Registered users will be entitled to support, upgrades (V2.20 was released to Registered users at the beginning of 1987), and help with DIREDIT-related problems (including telephone support) for a year from the date of registration. Documentation for DIREDIT V1.51 Copyright 1986, P. R. Fletcher ________________________________ _______________________________ INTRODUCTION ____________ DIREDIT is a program which allows you to "edit" DOS directories. There are a number of programs, some in the public domain, others available as components of commercial utility packages (e.g. the Norton Utilities (TM)), which allow directories to be sorted in various ways ______ (by filename, by file type ("extension"), by modification date, by size), but DIREDIT is (as far as I know) the only one which also allows the user to specify an arbitrary order and/or to move individual directory entries around at will. DIREDIT also displays the directory in a very compact manner, with up to 80 file-names visible on the screen at once, but allows you to see the full file description for any entry simply by moving a cursor to the name. You may reasonably ask why you should care how your directories are arranged - one answer to this question depends on the fact that the order in which subdirectories and files are listed in the order in which DOS searches through them (when asked to find a data file or executable program). It follows from this that programs and data files will be accessed fastest if they appear at the top of the directory listing of the subdirectory in which they are found, and also that subdirectories (especially those which are specified in your PATH command) should, for fast access, be at the top of the directory listing. On the other hand, many people find it easier to find a file that they are searching for if the directory is sorted in some other way. The advantages (in this context) of alphabetical sorts by name and/or type are obvious, but sorting by size or date/time (most recently modified files at the bottom) can also sometimes be useful. You can use DIREDIT for both purposes - arranging your directories on disk for efficient access and then resorting them temporarily on the screen when searching for a file without (necessarily) saving the resorted directory to disk. DIREDIT is distributed as "User-supported Software". If, after trying it out, you decide to continue to use it, you should become a registered user by sending a completed copy of the Registration Form (which is included in this documentation), together with a check or money order for $20.00 ($10.00 for Registered Users of HDTEST) to me at the address which appears on the form (and on the program's copyright screen). I will register you for a year's support. Registration entitles you to be notified of upgrades, bug fixes, newly discovered incompatibilities, etc., and to ask for (and get) necessary help in adapting the program to work on your hardware. I cannot guar- antee to make DIREDIT work with every possible combination of hardware and software, but I will promise to try to solve problems as they come up, and I will return your registration fee if I cannot support the program on your system. Support will be available TO REGISTERED USERS ___________________ ONLY by mail, BIXmail, Compuserve EMail and, for an experimental ____ period, telephone. Please also bear in mind that my willingness and ability to continue to support and enhance these programs will be directly dependent on your willingness to pay the registration fee and (to some extent) inversely dependent on the number of questions I get that could be answered by reading the documentation(!). DIREDIT was written principally in C, compiled by the Microsoft C Page 2 Documentation for DIREDIT V1.51 Copyright 1986, P. R. Fletcher ________________________________ _______________________________ compiler (Version 4.00) using its "small" memory model, and linked with code from the distributed Microsoft C object libraries using the Microsoft LINK program (Version 3.51). Additional assembly language routines were assembled by the Microsoft MASM Macro Assembler (Version 4.00). Portions of the distributed program are consequently Copyright (C) by Microsoft Corp., 1985, 1986. All rights reserved. These portions are used under the terms of a license from Microsoft Corp. DIREDIT was written with care and has been tested on a number of different systems. I cannot, however, give any guarantee as to their performance on a specific system, nor can I accept liability for any actual or consequential loss resulting from their use. The programs may only be used and/or copied in their original form. Unauthorised modifications and/or the use of all or part of the program in other software, commercial or otherwise, are strictly prohibited. HARDWARE & SOFTWARE REQUIREMENTS ________________________________ DIREDIT makes a number of assumptions about the environment in which it is operating. The program will, generally speaking, abort with an informative error message if it finds one of these assumptions to be untrue! It requires MS/PC-DOS 2.x or above and about 96 Kb of free memory (the exact amount required depends on the size of the target directory) to run. The device on which the target directory is found must have been initialized by FDISK and FORMATted by the DOS utility. DIREDIT uses BIOS calls to read and write the directory information, so the BIOS handler for interrupt 13 must be capable of handling (at least) normal disk reads and writes (sub-functions 2 and 3) in a way that is compatible with that documented for the XT disk adapter in IBM's technical documentation. This should be no problem for most disk systems on IBM PCs and most compatibles. This version of DIREDIT may ___ not, however, be usable on non-bootable hard disks and/or on hard disks which require special device drivers to be installed. A forthcoming release of DIREDIT (which should be available to registered users by the end of December, 1986) should be usable on almost any DOS disk device, without requiring BIOS compatibility. An ANSI screen driver should be installed on those systems (including IBM PCs) which do not support ANSI screen I/O in Video BIOS. The program's screen output speed will benefit significantly from the use of one of the enhanced ANSI drivers that are available (FANSI-Console, NANSI, etc.), but it will operate correctly (if more slowly) with Microsoft's ANSI.SYS. Page 3 Documentation for DIREDIT V1.51 Copyright 1986, P. R. Fletcher ________________________________ _______________________________ RUNNING DIREDIT _______________ The program is invoked with the command: DIREDIT [pathname] If a pathname is not specified on the command line, the program will default to that of the current directory. Otherwise, any valid DOS path specification may be used (some examples are: A:\; A:\SUB1\SUB2; \SUB1\SUB2 {referred to the root directory of the current device}; SUB3\SUB4 {starting from the current directory}). Note that there is one difference between the way DIREDIT interprets path specifications and the way DOS normally does. DIREDIT will interpret a specification which contains a drive but no path (e.g. A:) as referring to the root ____ directory on the specified drive, rather than the default directory on _______ that drive (if one has been named in a "CD" command). DIREDIT will display its copyright screen and pause until you press a key - it will then read in the directory to be edited and check to see whether the first file or files in the directory have the "System" attribute. If they do (typically true for the files that contain the resident component of the operating system on the root directory of a bootable disk), DIREDIT asks whether you wish to exclude these files from directory sort operations. You should not override the default ("Y") answer to this question unless you are sure you know what you are doing - if the operating system files are not first in the directory, the disk will cease to be bootable. After you have responded to this question (assuming that it was necessary for DIREDIT to ask it) the program will switch to its normal display mode. On the upper 20 lines of the terminal screen are displayed up to 80 "identifier blocks", each comprising an ID number (which initially corresponds to the position of the directory entry in the directory) and a file name. An inverse video box cursor, initially positioned over the first (top lefthand) block, indicates the current entry. This box can be moved to highlight any visible block by using the arrow keys. The "Cursor->" display line at the bottom of the screen shows the full description of the file or directory whose name is in the current block. If there are less than 81 active directory entries (the normal case!), all will be displayed all the time, otherwise only the first 80 will be visible. THE SCREEN DISPLAY __________________ The names and ID numbers of up to 80 files and/or subdirectories are displayed on the screen at once. If the directory being edited contains more than this number of entries, DIREDIT allows you to "page" up and down within the directory so that you can inspect or operate on any entry. In this case, the screen is divisible into two windows by a line drawn vertically down its center. The right-hand window will always contain 40 blocks; the left-hand one will contain up to 40 more. Each window may be positioned (using the <PgUp>, <PgDn>, <Home>, and <End> keys) anywhere within the directory, except that the two windows may never overlap and that the left hand window must always remain "below" the right hand one in the directory. When Page 4 Documentation for DIREDIT V1.51 Copyright 1986, P. R. Fletcher ________________________________ _______________________________ the program starts up, the two windows are "locked", so that they move together. Pressing the "L" key toggles the lock so that they can move independently. <PgUp> moves the current window (i.e. the one which contains the block cursor) up by twenty entries. <PgDn> moves the current window down by twenty entries. <Home> moves the current window as far towards the beginning of the directory as possible (so that is shows the first 40 entries). <End> moves the current window as far towards the bottom of the directory as possible (to show the last 21 to 40 entries). If the windows are not "locked" together and an attempted window move would cause them to overlap (i.e. the inactive window is immediately adjacent to the current one in the direction of the attempted move) OR the windows are "locked" together (which is the default case), both windows are moved. If an attempted window move would cause either window to go off the top or bottom of the file, it does not take place and the attempt is simply ignored. Note that window moves do not affect the position of the cursor within the window. _________________ EDITING THE DIRECTORY _____________________ The simplest way of making small changes to the organization of the directory is by moving individual entries. An individual entry is moved by positioning the cursor on the identifier block, "picking it up" by pressing the <Del> key, positioning the cursor at the point to which the entry is to be moved, and "inserting" it there by pressing the <Ins> key. The full description of the entry that is in the process of being moved is shown on the "Moving->" display at the bottom of the screen. You may not exit (which causes the disk directory to be updated, and would, in this case, cause the "moving" entry to be lost) while an entry is being moved - you must replace it somewhere first. An entry which is being moved is also automatically put back (at the current cursor position) before a sort operation is carried out. Note that you can move "System" entries from the ___ beginning of the root directory manually, but you will be prompted for ________ confirmation before you can "pick them up". A number of other single-key commands are implemented, as described below. Many of them trigger short dialogues, and the commands with potentially far-reaching effects usually require confirmation before you are allowed to do something you might regret. Note that, although the editor commands do not require that the <Return> key be pressed also, responses to prompts always do. "D" - change the date stamp on the current file. The program prompts with the current date stamp - the new date should be entered in the same format. Invalid dates will be rejected but any valid date between January 1, 1980 and December 31, 2099 may be entered. "L" - toggle the "lock" which (by default) forces both windows to move together. This has no perceptible effect unless there are more than 80 Page 5 Documentation for DIREDIT V1.51 Copyright 1986, P. R. Fletcher ________________________________ _______________________________ entries in the directory. "M" - display the next of a series of single-line "aides-memoire" to available commands which appear on the 23rd line of the screen. Repeatedly pressing this key will cycle through lines describing all valid commands. "N" - edit a new directory (you are automatically given the option of writing the one currently being edited to disk first, if changes have been made to it). "Q" - quit the program without updating the current directory. If you _______ have made any changes during the current session, the program will prompt for confirmation before actually quitting. "R" - rename the current file. The program will prompt you to enter the new name. Invalid names (too long, containing illegal characters, etc.) will be rejected, as will a name that is the same as one of another file entry in the current directory. "S" - sort the directory (see below). "X" - exit and (if any changes have been made) update the current directory. "?" or <F1> - display help text. SORTING THE DIRECTORY _____________________ The directory display (and, ultimately, the directory on disk) may be sorted by date, filename, extension, or file size, in ascending or descending order. It may also be rearranged in any other arbitrary order you care to specify. When you enter "S", the program will determine, by asking you a series of questions, how you want the directory to be sorted. The first option presented is: "User-Specified Order?" - responding to this prompt by entering "Y" allows you to rearrange the file entries in an arbitrary order. You will then be prompted to enter two lists of file numbers (the numbers displayed next to the filenames on the screen). The first list should contain the numbers of files which you would like to move to the top of the directory (in the order in which you want them to appear there) - the second should contain the numbers of files which you want to move to the bottom, also in the order in which they are to appear. Either list may be empty (just press <Return>). The lists should contain only the file numbers, as decimal integers, separated by one or more spaces and/or tabs. A final prompt requires that you specify [A]scending or [D]escending order - specifying [D]escending order simply reverses the order of all the files in the directory after your specified files have been moved to _____ the top and/or the bottom of the (otherwise) current version. Other possible sort orders are presented in turn as options if "User- Specified Order?" is rejected. These are "Sort by Filename?" (which actually sorts by name and extension), "Sort by Extension?" (which Page 6 Documentation for DIREDIT V1.51 Copyright 1986, P. R. Fletcher ________________________________ _______________________________ sorts by extension first, then by filename for files with the same extension), "Sort by Date/Time?" (which sorts by file date, then by time), and "Sort by file size?". Whichever of these is accepted, the program asks that you also specify [A]scending or [Descending order before proceeding with the sort. "System" files at the beginning of a directory will be excluded from all sorts unless specifically included (by a "N" response when the __ program asks you whether you want them excluded). In fact, if you have moved such a file manually to some other position, any sort will result in its being put back where it came from. IMPORTANT NOTE ______________ You should always review the directory you have been editing (by using the DOS DIR command) after exiting from DIREDIT, in order to check that it looks the way it should. If it doesn't look right, before ______ doing anything else, run CHKDSK or reboot the system and check it ___________________ again - if it still doesn't look right, you will have to DIREDIT it again. These precautions are advised because DOS keeps up to 99 sectors worth of data (including directory data) from your disks in memory (the actual number of sectors held in this way is set by the "BUFFERS=..." line in CONFIG.SYS, and defaults to 2 in PCs and XTs and 3 in ATs). If you use DIREDIT (which reads and writes the directory sectors without using DOS functions) to change a directory that DOS is holding in memory, that internal representation of the directory is not automatically updated. This presents a potential problem because, ___ if you were then to do something that changed the directory (write a new file, change an old file, etc.) from within DOS, DOS would make the appropriate changes to its copy of the (old) directory and write ___ it back over the new directory. Because there is no way of telling DOS ____ that the contents of its sector buffers may be invalid, DIREDIT attempts to flush them (before exiting) by performing a number of manoeuvres which result in multiple DOS disk read operations. It is ____ possible (though not very likely) that there are circumstances under which DIREDIT will fail to flush the DOS sector buffers - running CHKDSK always seems to flush them successfully, and rebooting is guaranteed to do so. Page 7 Documentation for DIREDIT V1.51 Copyright 1986, P. R. Fletcher ________________________________ _______________________________ LIMITATIONS AND RESTRICTIONS ____________________________ The current version of DIREDIT has a few limitations, which result from the way data is stored internally by the program. They are not "etched in stone", although the second could be avoided only with considerable difficulty. They are as follows: 1) Maximum number of clusters per disk = 28,000 (this number is approximate, because it depends on dynamic memory allocation). This limit may be increased to 32,768 in a subsequent version of the program. 2) Maximum cluster size = 65,535 bytes. I do not believe that a DOS disk can ever have clusters larger than 64 Kb, but my limit is one less than that and may, since sector and cluster sizes tend to run in powers of 2, effectively limit cluster size to 32 Kb - this should be enough for most people!. 3) Screen update speed is less than earth-shatteringly fast (!). This is on top of my list of things to be improved in V2.00. BUGS AND OTHER UNPLEASANT SUBJECTS __________________________________ Although, like all programmers, I sometimes like to think that my product is perfect, it is possible that there are a few bugs lurking in the depths of the program, and likely that some combination of software and hardware exists which DIREDIT cannot figure out and/or cope with. If you think you have found a bug and/or if you cannot get the program to work on your system, do the following: 1) Reread this documentation! Make sure that you are doing exactly what the documentation and/or program prompts tell you to do. Make sure (if you are trying to edit a directory on a drive with removable media) that the media is not write-protected. 2) Boot your system from a "virgin" DOS disk - preferably a copy of your DOS distribution disk - and try to run DIREDIT again. If the program runs in this limited environment, but not in your normal DOS environment, try reconstructing the system under which it failed (by adding things one by one until the problem recurs) and let me know about the incompatibility. 3) If the above approaches do not help, send me as detailed a description of the problem as possible and (IF you are a registered _______________________ user) I will do my best to diagnose and fix it. If you are not a ____ registered user, my interest in solving your problem is likely to depend on how probable I think it is that you have found a bug rather than an incompatibility. A bug/incompatibility report should always ______ include a full description of the system (software and hardware) on ____ which the program is being run. CHANGES FROM PREVIOUS VERSIONS ______________________________ The first version of DIREDIT that was generally released was V1.20. Page 8 Documentation for DIREDIT V1.51 Copyright 1986, P. R. Fletcher ________________________________ _______________________________ This version embodies the following changes/bug fixes: 1) Bug causing sorts by file size to result in incorrect ordering under some circumstances fixed (at V1.30). 2) Bugs causing improper operation of the [R]ename option fixed (at V1.50). 3) Bug causing the program to abort with a "Non-existent or Invalid Directory" error if the program were given a path specification containing only a drive name (e.g. A:) fixed (at V1.35). 4) Memory allocation/deallocation problem causing the program to abort with a "Invalid Device" error after the "N" option is used to edit a (variable) number of directories fixed (at V1.40). 5) ANSI driver reset to normal mode (insert line feed after 80th successive printable character output to screen) when program exits (at V1.40). 6) Ability to use the faster screen output mode provided by certain ANSI enhancers added (at V1.30). 7) Changes to program logic to reduce unnecessary screen updating (at V1.35). Page 9 Documentation for DIREDIT V1.51 Copyright 1986, P. R. Fletcher ________________________________ _______________________________ APPENDIX - SUMMARY OF SINGLE-KEY COMMANDS _________________________________________ <PgUp> - move the current window up by twenty entries. <PgDn> - move the current window down by twenty entries. <Home> - move the current window as far towards the beginning of the directory as possible. <End> - move the current window as far towards the bottom of the directory as possible. <Del> - "pick up" directory entry for move. <Ins> - "put down" directory entry. "D" - change the date stamp on the current file. "L" - toggle the "lock" which (by default) forces both windows to move together. "M" - display the next of a series of single-line "aides-memoire" to available commands which appear on the 23rd line of the screen. "N" - edit a new directory. "Q" - quit the program without updating the current directory. _______ "R" - rename the current file. "S" - sort the directory. "X" - exit and (if any changes have been made) update the current directory. "?" or <F1> - display help text. Page 10 REGISTRATION FORM - DIREDIT V1.51 _________________________________ Please complete this form and return it with a check or money order (no cash, please) for $20.00 ($30.00 Canadian, L15.00 Sterling) to: Peter R. Fletcher 1515 West Montgomery Avenue Rosemont PA 19010 U.S.A. None of the information on this form will be passed on to any other individual or commercial organization. Use the back of the form for comments or additional space. -------------------------------------------------------------------------- This information is required to process your Registration: Last Name:____________________________ Other Names:______________________ Address:______________________________ Town/City:________________________ State:_____________ Post Code:____________ Telephone:_________________ (evenings/weekends) I understand that this software is supplied without warranty, express or implied, and agree not to hold its author liable for any direct or consequential loss arising out of my use of it. Signature:______________________________ ------------------------------------------------------------------------- You are requested, but not required, also to answer the following questions: On What type(s) of computer are you using DIREDIT? ______________________ CPU (8088, 8086, etc.)? __________ Amount of RAM (kB)? ____________ Type & Size of Hard Disk(s)? ____________________________________ Make and Type of Hard Disk Controller(s)? ______________________________ Do you own a Modem? Y N Are you a member of BIX? Y N Compuserve? Y N Do you own or have access to a Cauzin Softstrip Reader Y N Did you think that the $20.00 registration fee for this program was: Very Good Value? About Right? Excessively High? Are there any other utility programs that you would like to see made available as "User Supported Software"? What sort of programs?